TextRange对象参考

原文来自TextRange object。
textRange对象代表document中一个连续的部分。

TextRange对象为实现一些实用功能提供了几个属性和方法。利用TextRange对象，你可以取得并修改文档的任意部分；你可以得到文档中的一个连续部分的定位以及一些其它的几何属性；你可以取得并修改文档中已选中的内容。

Internet Explorer以及部分Opera浏览器支持TextRange对象。

在火狐、Opera、Google Chrome以及Safari中，Range对象提供了简单的功能。Internet Explorer 9.0以后的版本同样支持Range对象。

因为所有的现代浏览器都支持Range对象，只有在Range对象不被支持的情况下才使用TextRange对象。本文后面的内容将一起介绍这两个对象。

创建一个TextRange对象有三个方法：

• 通过createTextRange方法创建一个TextRange对象。body对象以及一些其它的HTML元素支持createTextRange方法。新创建的TextRange对象的边界点（开始点和结束点）与这些HTML元素的内容对齐。
  
  
  • 你可以使用document.createRange方法创建一个空的Range对象。后面的章节描述了修改一个Range对象的边界点的方法。

• 在Internet Explorer中，有三种不同类型的选区（selection）：

  • 控件选区 - 选区包含了控件。
  • 文本选区 - 选区只包含文本。
  • 空选区 - 即没有选区（或者说选中的内容是不可用的）。

  利用selection对象的type属性可以得到选区的类型。当选区包含文本或者没有选中的内容时，用selection对象的createRange方法可以取得一个TextRange对象。返回的TextRange对象的边界点与选区的内容对齐。

  为了得到选区的内容，selection对象还支持其它的方法，比如说createRangeCollection方法，它返回一个TextRanges集合，包含了若干个TextRange对象。每个TextRange对象代表这个选区的一个连续部分。该createRangeCollection方法对多重选区来说很有用。但是Internet Explorer不支持它。所以使用createRange方法就足够了。

  使用selectionRange对象的getRangeAt方法可以取得一个代表当前选区的Range对象。selectRange对象可以包含超过一个Range对象。每个Range对象代表选区的一个连续部分。

  在Internet Explorer、Opera、Google Chrome、Safari以及低于3.0版本的火狐浏览器中，至少有一个Range对象属于selectionRange对象，因为文本选区永远是一个DOM层次结构的连续部分。

  在3.0版以后的火狐浏览器中，鼠标选网页内容时按住Ctrl键，可以选中多个文本域。如果你想选中离散的文本块，请使用addRange方法。

• 使用duplicate方法可以复制出一个已有的TextRange对象的副本。返回的对象与原始对象完全相同。

如果已存在一个TextRange对象的实例，你可以用下面的方法修改它的边界：

• 如果你想把一个TextRange对象的边界点与一个元素的内容对齐，而且这个元素支持createTextRange方法，请在这个元素上使用createTextRange方法。对其它元素，请使用body.createTextRange方法来创建一个TExtRange对象，并对这个必要的元素使用moveToElementText方法。

  如果你想把一个Range对象的边界点与一个元素或元素的内容对齐，请使用selectNode或selectNodeContents方法。

• 使用moveStart方法和moveEnd方法可以移动一个TextRange对象的开始点的结束点。如果你想把一个TextRange对象的开始点和结束点与另一个TextRange对象的开始点和结束点对齐，请使用setEndPoint方法。

  如果你想分别地修改一个Range的开始点和结束点，请使用setStart方法、setStartBefore方法、setStartAfter方法，以及setEnd方法、setEndBefore方法、setEndAfter方法。

• 利用collapse方法，你可以移动开始点或者结束点，反之亦然。TextRange对象和Range对象都可以用这个方法。

• 扩展TextRange对象的内容，请使用expand方法以实现它。

如果你一个TextRange对象的定位，你可以：

• 利用offsetLeftc以及offsetTop属性，可以得到该TextRange对象的坐标。不能取得该元素以及一个TextRamge对象用开始点和结束点定义的偏移。

  • 如果你要取得一个TextRange对象的矩形边界，请使用boundingLeft、boundingTop、boundWidth以及boundingHeight属性。

  • 如果你要取得一个TextRange对象的准确形状，请使用getClientRects方法。它将取得一个TextRectangles集合，包含了几个TextRectangle对象。每个TextRectangle对象代表属于这个TextRange对象的一行文本。

  上面的提到所有的坐标都是相对于浏览器窗口的左上角的。

  • document.elementFromPoint方法可以帮助你取得位于指定坐标上的元素。

  • 这个包含了整个TextRange对象的元素，如果你想要取得它在DOM层次结构中元素的深度，请使用parentElement方法。

  一个Range对象是用开始点和结束点定义的。一个元素以及一个位置定义了一个点。如果这个元素只有文本内容（TextNode、CDATASection或者CommentNode），这个位置指定了元素中的一个字符位置；如果这个元素并非只有文本内容，这个位置指定了元素中一个子元素的序号索引。

  和(endContainer,endOffset)属性指定了一个Range对象的开始点和结束点。startOffset属性指定在这个startContainer元素中Range开始的位置。endOffset属性指定了在这个endContainer元素中Range结束的位置。

  如果你想取得包含了整个Range对象的元素在DOM层次结构中节点的深度，请使用commonAncestorContainer属性。

• 当一个TextRange的开始点和结束点是同一个位置的时候，这个TextRange对象就是收缩的。你可以用多种方法来检测它是否处于收缩状态。比如说，用TextRange对象的文本内容来检测。用text属性可取得一个TextRange对象的文本内容，并作为字符串来对待。如果这个text属性代表的字符串的长度返回0，则TextRange对象是收缩的。

  使用collapsed方法可以检测Range对象是否处于收缩状态。

• 比较两个TextRange对象的定位，可以使用compareEndPoints方法。它比较了这些对象的边界点。

  要想检测一个TextRange对象是否包含另一个TextRange对象，可以用inRange方法。isEqual方法检测两个TextRange对象是否是完全相同的。

  两个Range对象的定位可以通过compareboundaryPoint方法来比较。它比较了这些对象的边界，类似于TextRange对象中的compareEndPoints方法。

  请注意，虽然compareboundaryPoints方法和compareEndPoints方法的语法是相似的，但是同样的案例，在不同的浏览器中，它们的行为是不同的。请阅读这两个方法的页面以了解详细区别。

  如果你想检测一个点（一个(element,position)对，其中position指定了element内部的一个索引或者说一个字符位置）是否位于一个Range内部，请使用comparePoint或者isPointInRange方法。

操作一个TextRange对象的内容：

• text属性能够设置或取得一个TextRange对象的文本内容，作为一个字符串。

  如果你需要HTML格式的内容，请使用htmlText属性。

  如果要替换一个带有HTML格式文本的TextRange对象的内容，请使用pasteHTML方法。你还可以用这个方法来删除这些内容（只需要在调用pasteHTML时用空字符串作为参数。）

  toString方法取得一个Range对象的文本内容，作为一个字符串。

  • 如果你需要以层次结构DOM的形式取得一个Range对象的内容，请使用cloneContents方法和extractContents方法。这两个方法会从Range内容中建立一个DocumentFragment对象。
  • 要想从document中移除一个Range对象的内容，请使用deleteContents方法。
  • 要想向Range对象中插入一个新元素，请使用insertNode方法。

选择一个TextRange对象的内容：

• 直接调用TextRange对象的select方法（多文本选区中这个方法不可用）。
  > 首先调用window.getSelection方法来接收一个从属于当前选区的selectionRange对象。如果你想给当前选区 添加一个Range的内容，直接调用addRange方法就可以把这个Range对象添加到selectionRange对象中。如果你只想要一个被选中的Range的内容，在调用addRange方法加入这个Range对象之前，先调用selectionRange对象的removeAllRanges方法。

TextRange对象的一些额外的功能：

• 可以用execCommand方法编辑一个TextRange对象的内容，就像在富文本编辑器中那样。你可以修改背景色或者前景色，你可以使字体变成粗体、斜体，你可以用剪贴板剪切、复制以及粘贴内容，它提供了一些其它的功能。

• 用getBookmark方法，可以把一个TextRange对象保存为bookmark。之后可以用moveToBookmark方法创建一个TextRange对象。该bookmark，以及这个用moveToBookmark方法创建的TextRange对象与被保存的那个TextRange对象是完全相同的。

语法：

用下面的方法可以访问textRange对象：

• selection.createRange()
• object.createTextRange()
• TextRanges.item(index)

可能的成员：

属性：

属性名	说明
boundingHeight	返回一个整型值，指定了当前的TextRange对象的边界矩形的高度，以像素为单位。
boundingLeft	返回一个整型数，指定了当前的TextRange对象的边界矩形的左边缘坐标，以像素为单位。
boundingTop	返回一个整型数，指定了当前的TextRange对象的边界矩形的上边缘坐标，以像素为单位。
boundingWidth	返回一个整型数，指定了当前TextRange对象的边界矩形的宽度，以像素为单位。
htmlText	返回属于一个TextRange对象的HTML源码，作为一个字符串。
offsetLeft	返回一个对象相对于它的定位父元素[1]的左边缘的左坐标位置，以像素为单位。
offsetTop	返回一个对象相对于它的定位父元素[1]的顶边缘的顶坐标位置，以像素为单位。
text	用一个字符串设置一个TextRange对象内部的文本，或者返回一个TextRange对象内部的文本，作为一个字符串。

方法

方法名	说明
collapse	把一个range对象的开始点移动到它的结束点，或者相反。
compareEndPoints	比较两个textRange对象的开始点和结束点的位置。
duplicate	返回当前TextRange对象的一个精确的复制副本。
execCommand	在某个对象上运行commands
expand	用一个字符、句子或者词语，在插入点扩展TextRange对象的内容。
findText	在document中查找指定的文本，并关联到一个TextRange对象。
getBookmark	把当前的TextRange对象保存到一个字符串中，之后可以用moveToBookmark方法返回原始的TextRange对象。
getBoundingClientRect	返回一个TextRectangle对象，指定当前元素或者TextRange对象的边界矩形，以像素为单位，相对于浏览器窗口的左上角。
getClientRects	返回一个TextRectangles集合，指定当前元素或者TextRange对象的精确形状。
inRange	返回当前TextRange对象是否包含了指定的TextRange对象。
isEqual	返回当前的TextRange对象是否与指定的TextRange对象完全相同。
move	把当前的TextRange对象的结束点移到它的开始点，并把这个收缩的TextRange对象移动指定的字距。
moveEnd	把当前的TextRange对象的结束点移动指定字距。
moveStart	把当前的TextRange对象的开始点移动指定字距。
moveToBookmark	把当前的TextRange对象的开始点和结束点移到指定bookmark代表的位置。
moveToElementText	把当前的TextRange对象的开始点和结束点对齐到指定的元素的文本内容。
moveToPoint	把当前的TextRange对象的开始点和结束点移动到指定的位置。
parentElement	返回在DOM层次结构中包含了整个TextRange对象的最深的节点的引用。
pasteHTML	把当前TextRange对象的内容替换为指定的HTML格式的文本。
queryCommandEnabled	用execCommand方法，返回这个指定的command是否能被执行成功。
queryCommandIndeterm	返回指定的command是否在一个不确定的状态中。
queryCommandState	返回指定的command当前的状态
queryCommandSupported	返回当前的对象是否支持指定的command。
queryCommandText	返回指定的command的说明描述。
queryCommandValue	返回指定的command的实际的值。
scrollIntoView	把指定的元素滚致到文档的可见区域。
select	选择包含在当前TextRange或者controlRange对象中的所有的文本或控件。
setEndPoint	把当前TextRange对象的开始点和结束点对齐到指定的TextRange对象的开始点和结束点。

[1]定位父元素（offsetParent）：定位父元素并非是DOM层次结构中的parentElement，而是离该元素最近的一个position属性为relative、absolute、static的上层级元素。如果上层级元素中没有这样的元素，则定位父元素就是document.body。

HTML代码示例1：

这个示例演示了一个在document中取得选中内容的跨浏览器解决方案。

HTML<head>
    <script type="text/javascript">
        function TestSelection () {
            if (window.getSelection) {  // all browsers, except IE before version 9
                var selectionRange = window.getSelection ();                                        
                alert ("The text content of the selection:\n" + selectionRange.toString ());
            } 
            else {
                if (document.selection.type == 'None') {
                    alert ("No content is selected, or the selected content is not available!");
                }
                else {
                    var textRange = document.selection.createRange ();
                    alert ("The text content of the selection:\n" + textRange.text);
                }
            }
        }
    </script>
</head>
<body>
    Select some text or <button>element</button>, or do not select anything, before you click on the button below.
    <br /><br />
    <button onclick="TestSelection ();">Test the selection!</button>
</body>

HTML代码示例2：

这个跨浏览器解示例演示了如何用range对象删除一个元素中的内容：

HTML<head>
    <script type="text/javascript">
        function RemoveContent () {
            var srcObj = document.getElementById ("src");

            if (document.createRange) {     // all browsers, except IE before version 9
                var rangeObj = document.createRange ();
                rangeObj.selectNodeContents (srcObj);
                rangeObj.deleteContents ();
            }
            else {      // Internet Explorer before version 9
                var rangeObj = document.body.createTextRange ();
                rangeObj.moveToElementText (srcObj);
                rangeObj.select ();
                rangeObj.execCommand ('cut');
            }
        }
    </script>
</head>
<body>
    <div id="src" style="background-color:#e0a0b0; width:300px; height:50px;">The <b>contents</b> of the <i>source</i> element.</div>
    <br /><br />
    <button onclick="RemoveContent ();">Remove the contents of the source element!</button>
</body>